home *** CD-ROM | disk | FTP | other *** search
/ STraTOS 1997 April & May / STraTOS 1 - 1997 April & May.iso / CD01 / INTERNET / SITES / LITTLE / P3SRC.ZIP / COMPILE.DOC
Encoding:
Text File  |  1996-07-08  |  8.0 KB  |  170 lines
  1. COMPILING SOURCE CODE DOCUMENTATION FOR POV-Ray 3.0
  2.  
  3. 1.0   INTRODUCTION AND DISCLAIMERS
  4.  
  5. This documentation is to help you compile the portable C source code into a 
  6. working executable version of POV-Ray.  This is only for those people who 
  7. want to compile a custom version of POV-Ray or to port it to an unsupported 
  8. platform or compiler.  
  9.  
  10. This documentation DOES NOT tell you how to use POV-Ray.  User 
  11. documentation, sample scenes and scene "include" files are in the archives 
  12. which contain the pre-compiled executable versions or as a separate archive 
  13. for Unix users who have no official executable versions.  You MUST HAVE the 
  14. user documentation and sample scenes to use POV-Ray. See the file 
  15. POVWHERE.GET for details on what to get and where to get it.
  16.  
  17. The first question you should ask yourself before proceeding is "Do I 
  18. really need to compile POV-Ray at all?"  Official POV-Ray Team executable 
  19. versions are available for MS-Dos, Windows 3.1x/95/NT, Mac 68k, Mac Power 
  20. PC, Amiga, Linux for Intel x86, and SunOS.  Other unofficial compiles may 
  21. soon be available for other platforms.  If you do not intend to add any 
  22. custom or experimental features to the program, and if an executable 
  23. already exists for your platform then you need not compile this program 
  24. yourself.
  25.  
  26. If you do want to proceed, you should be aware that you are very nearly on 
  27. your own.  This documentation and other related compiling documentation 
  28. assumes you know what you are doing.  It assumes you have an adequate C 
  29. compiler installed and working.  It assumes you know how to compile and 
  30. link large, multi-part programs using a "make" utility or an IDE project 
  31. file if your compiler supports them.  Because makefiles and project files 
  32. often specify drive, directory or path information, we cannot promise our 
  33. makefiles or projects will work on your system.  We assume you know how to 
  34. make changes to makefiles and projects to specify where your system 
  35. libraries and other necessary files are located.
  36.  
  37. In general you should not expect any technical support from the POV-Ray 
  38. Team on how to compile the program.  Everything is provided here "as is".  
  39. All we can say with any certainty is that we were able to compile it on our 
  40. systems.  If it doesn't work for you, we probably cannot tell you why.
  41.  
  42. There is no technical documentation for the source code itself except for 
  43. the comments in the source files.  We try our best to write clear, well-
  44. commented code but some sections are barely commented at all and some 
  45. comments may be out dated.  We do not provide any technical support to help 
  46. you to add features.  We do not explain how a particular feature works.  In 
  47. some instances, the person who wrote a part of the program is no longer 
  48. active in the Team and we don't know exactly how it works.
  49.  
  50. When making any custom version of POV-Ray or any unofficial compile, please 
  51. make sure you read and follow all provisions of our license in the file 
  52. POVLEGAL.DOC.  In general you can modify and use POV-Ray on your own 
  53. however you want but if you distribute your unofficial version you must 
  54. follow our rules.  You may not under any circumstances use portions of POV-
  55. Ray source code in other programs.
  56.  
  57.  
  58. 2.0   DIRECTORY STRUCTURE
  59.  
  60. POV-Ray source code is distributed in archives with files arranged in a 
  61. particular hierarchy of directories or folders.  When extracting the 
  62. archives, you should do so in a way that keeps the directory structure 
  63. intact.  In general we suggest you create a directory called \povray3 and 
  64. extract the files from there.  The extraction will create a directory 
  65. called "source" with many files and sub-directories from it.  
  66.  
  67. In general, there are separate archives for each hardware platform and 
  68. operating system but each of these archives may support more than one 
  69. compiler.  For example here is the directory structure for the MS-Dos 
  70. archive.
  71.  
  72.    SOURCE
  73.    SOURCE\LIBPNG
  74.    SOURCE\ZLIB
  75.    SOURCE\MSDOS
  76.    SOURCE\MSDOS\PMODE
  77.    SOURCE\MSDOS\ZTIMER
  78.    SOURCE\MSDOS\BORLAND
  79.    SOURCE\MSDOS\DJGPP
  80.    SOURCE\MSDOS\WATCOM
  81.  
  82. The SOURCE directory contains source files for the generic parts of POV-Ray 
  83. that are the same on all platforms.  The SOURCE\LIBPNG contains files for 
  84. compiling a library of routines used in reading and writing PNG (Portable 
  85. Network Graphics) image files.  The SOURCE\ZLIB contains files for 
  86. compiling a library of routines used by LIBPNG to compress and uncompress 
  87. data streams.  All of these files are used by all platforms and compilers.  
  88. They are in every version of the source archives.
  89.  
  90. The SOURCE\MSDOS directory contains source files for the MS-Dos version 
  91. that are common to all supported MS-Dos compilers.  The SOURCE\MSDOS\PMODE 
  92. SOURCE\MSDOS\ZTIMER directories contain source files for PMODE.LIB and
  93. ZTIMER.LIB which are required by all MS-Dos versions.  The 
  94. SOURCE\MSDOS\BORLAND, SOURCE\MSDOS\DJGPP, and SOURCE\MSDOS\WATCOM directories 
  95. contain source, makefiles and project files for C compilers by Borland, 
  96. DJGPP, and Watcom.  
  97.  
  98. The SOURCE\MSDOS directory is only in the MS-Dos archive.  Similarly the 
  99. Windows archive contains a SOURCE\WINDOWS directory.  The Unix archive 
  100. contains source/unix etc.
  101.  
  102. The SOURCE\MSDOS directory contains a file CMPL_MSD.DOC which contains 
  103. compiling information specific to the MS-Dos version.  Other platform 
  104. specific directories contain similar CMPL_xxx.DOC files and the compiler 
  105. specific sub-directories also contain compiler specific CMPL_xxx.DOC files.  
  106. Be sure to read all pertinent CMPL_xxx.DOC files for your platform and 
  107. compiler.
  108.  
  109.  
  110. 3.0   CONFIGURING POV-Ray SOURCE
  111.  
  112. Every platform has a header file "config.h" that is generally in the 
  113. platform specific directory but may be in the compiler specific directory.  
  114. Some platforms have multiple versions of this file and you may need to copy 
  115. or rename it as config.h.  This file is #included in every module of POV-
  116. Ray.  It contains any prototypes, macros or other definitions that may be 
  117. needed in the generic parts of POV-Ray but must be customized for a 
  118. particular platform or compiler.
  119.  
  120. For example different operating systems use different characters as a 
  121. separator between directories and file names.  MS-Dos uses back slash, Unix 
  122. a front slash, or Mac a colon.  The config.h file for MS-Dos and Windows 
  123. contains the following:
  124.  
  125.   #define FILENAME_SEPARATOR '\\'
  126.  
  127. which tells the generic part of POV-Ray to use a back slash.  
  128.  
  129. Every customization that the generic part of the code needs has a default 
  130. setting in the file SOURCE\FRAME.H which is also included in every module 
  131. after config.h.  The frame.h header contains many groups of defines such as 
  132. this:
  133.  
  134.   #ifndef FILENAME_SEPARATOR
  135.   #define FILENAME_SEPARATOR '/'
  136.   #endif
  137.  
  138. which basically says "if we didn't define this previously in config.h then 
  139. here's a default value."  See frame.h to see what other values you might 
  140. wish to configure.  
  141.  
  142. If any of the definitions are used to specify platform specific functions, 
  143. you should also include a prototype for that function.  For example the 
  144. file source\msdos\config.h not only contains the macro:
  145.  
  146.  #define POV_DISPLAY_INIT(w,h) MSDOS_Display_Init ((w), (h));
  147.  
  148. to define the name of the graphics display initialization function, it 
  149. contains the prototype:
  150.  
  151.  void MSDOS_Display_Init (int w, int h);
  152.  
  153. If you plan to port POV-Ray to an unsupported platform, you should probably 
  154. start with the simplest, non-display generic Unix version.  Then add new 
  155. custom pieces via the config.h file.
  156.  
  157.  
  158. 4.0   CONCLUSION
  159.  
  160. We understand that this file is only the most trivial first steps but half 
  161. the fun of working on POV-Ray source is digging in and figuring it out on 
  162. your own.  That's how the POV-Ray Team members got started.  We've tried to 
  163. make the code as clear as we can.
  164.  
  165. Be sure to read the CMPL_xxx.DOC files in your platform specific and 
  166. compiler specific directories for some more minor help if you are working 
  167. on a supported platform or compiler.
  168.  
  169. Good luck!
  170.